The engine gaps left open after the SDK batch (2026.9.12.2) - #619

Implements .agents/docs/2026-09-12-engine-gaps-after-the-sdk-batch.md, tasks M1 to M9, as one change carrying version 2026.9.12.2. 2026.9.12.1 (#617) was not published, and its CHANGELOG entry is folded into this version. The record's §11 lists the corrections made during implementation.

Changes

#618: a Windows GUI executable, declared on its target

• [targets.<name>] windows_subsystem = "console" | "windows" and windows_entry = "main" | "wmain" | "WinMain" | "wWinMain".
• The emitter renders them onto the declaring executable's own link edge only:
  • on the MSVC ABI, /SUBSYSTEM: together with /ENTRY:<entry>CRTStartup whenever either key differs from its default, spelled with -Wl, under a GNU-style driver;
  • on the GNU ABI, -mwindows and -municode;
  • nothing off PE.
• The ABI predicate is pe_msvc_abi, extracted from pe_link_flag, so the import library and the subsystem address the same linker.
• Both keys are refused on a library target, naming the target and the key. An unknown value is refused, naming the accepted values.
• The warning for an unsupported per-target key now lists the parser's own key table; the hand-written copy had omitted exports.
• Build-program protocol 10 adds mcpp:windows-subsystem=<target>:<value> and mcpp:windows-entry=<target>:<value>, with a new Scope::TargetLink. target_directive_error checks them against the manifest before apply, on both the run path and the cache-hit path.

T1: the fast path compares the toolchain request

• Measured before the fix: after a gcc build, mcpp build --toolchain llvm@22.1.8 printed Finished dev in 0.00s and left the gcc artefact in place.
• The build cache records toolchain= (the --toolchain override and [toolchain] default), and both the build and run fast paths compare it.
• The named set is the target triple, profile, cache mode, features and toolchain request. --offline, --locked and --jobs do not change what resolution chooses, so they are not compared.
• Revert probe: tests/e2e/645 fails with the 2026.9.11.4 binary at exactly that step.
• The fast path is taken only for ELF artefacts, and that predates this change (feat: converge template identity, runtime contracts, and release state #400): try_fast_build requires an ELF runtime-validation verdict for every artefact. On macOS and Windows CI, 645's control therefore found an unchanged second build resolving the toolchain. The test compares the toolchain= lines the two builds record: identical lines report the host as not measured, and differing lines fail. The record's §11 notes the limitation as outside this change.

#615: runtime.deploy

• [runtime] deploy = [{ from, to }] in mcpp.toml, and runtime.deploy in descriptors. Destinations are bin/<to>/<file>, and "." means beside the executable.
• One path rule applies to both parsers; each malformed entry is refused naming its index. Two sources for one destination are refused naming the destination.
• deploy is a key of its own because an older descriptor reader does not terminate on { inside deploy_files.
• The TOML array-of-tables allowlist gains runtime.deploy. The unit test written for the key reported that gap.
• mcpp pack stages the files of both deploy_files and deploy at the same relative path beside the packed executable, in both the ELF and PE layouts. Before this, pack read neither list.

[target.<selector>.abi] threads and requires_abi (record §5.2)

• A typed graph-wide switch, rendered as -pthread on targets that are neither PE nor freestanding. It is applied to the root's dialect_cxxflags, cflags and ldflags and to every dependency's cflags, so it reaches the std module prebuild, the scan, every translation unit, the link and the dependency cache key.
• requires_abi = { threads = true } on a package or a feature is refused before compilation when the root does not state the switch, naming the package, the feature and the table that satisfies it.
• A dependency's own [target.<selector>.abi] is reported (abi/dependency-table) and ignored.

#613: the install hook's environment

• A dependency's install hook receives MCPP_TARGET and its three segments, and MCPP_COMPILER and MCPP_CXX_STDLIB present and empty, so a hook never reads a value inherited from a parent process.
• The toolchain values are empty because prepare resolves the toolchain after the dependency graph: a package in the graph may supply a target-side layer. tests/e2e/648 measured this, and the record's §11 states that neither §2.4 criterion holds as written.
• install_hook_env computes the six values, and contract_env now takes them from it, in the same order, so no build program's re-run key changes.
• docs/06, docs/22 and docs/32 state the requires = ["mcpp:c++-abi=<stdlib>"] recipe for a source-built static package; the refusal names both implementations once the toolchain is resolved.

#614: one decision for an xlings invocation's environment

• invocation_env decides the environment: global mode is an absent XLINGS_PROJECT_DIR.
• POSIX renders the decision into the command prefix, which is byte-identical to the previous strings.
• On Windows, ScopedInvocationEnv applies the project scope for the lifetime of each runner function and restores the prior value. _putenv_s(key, "") already meant removal there; what was wrong was the lifetime.
• The POSIX install_packages fallback no longer spells global mode by hand.
• platform::env::unset is explicit.
• A failed install appends xlings' own error-level stderr lines (at most the last 20) to mcpp's diagnostic, through stderr_error_tail.

#609 and G1

• docs/20 gains a known toolchain hazard section for <xutility>: std::find no longer compiles with structs with defaulted equality comparison with Clang-CL microsoft/STL#6294.
• The [target.<selector>.xlings] refusal names [target.<selector>.xlings.workspace]. examples/13, its README and the iOS simulator CI fixture use that table.

Tests

Unit tests:

• test_manifest: windows keys, runtime.deploy, requires_abi and the abi table, the G1 refusal, and the generated key list.
• test_ninja_backend: every row of the subsystem rendering tables, plus a graph test showing the flag reaches only the declaring executable.
• test_build_directives: scope, refusals and cache round trip of the new directives.
• test_runtime_contract: the descriptor deploy reader.
• test_xlings: invocation_env, the restore guarantee and the POSIX prefix.
• test_install_hook_env: a new file.

All 112 unit test binaries pass locally.

End-to-end tests:

• 642 (native Windows, MSVC ABI) and 643 (mingw-cross, run under wine) read the PE Subsystem field from the image bytes and check that a static constructor runs before main.
• 644: the keys are inert and byte-identical on ELF, and the refusals fire.
• 645: the A-B-A fast-path request test, the mcpp run leg, and the machine-default leg (newest other installed version, checked in the artefact); reported as not measured on hosts whose fast path declines for another reason.
• 646: runtime.deploy placement, the test binary layout, the collision and the escape refusal.
• 647: the abi switch, its refusals, the dependency table, and the host inertness of a table scoped to emscripten.
• 648: a local-index install hook compiles in what it saw: the build's target, and empty toolchain names despite values exported by the parent.
• 649: mcpp pack carries both lists.

Ecosystem follow-ups (after release)

• E1, openkal-emscripten: the README correction, requires_abi on the threads feature, and the CI engine pin.
• E2, mcpp-index: compat.mysql-connector-cpp declares requires = ["mcpp:c++-abi=libstdc++"], checked against the index floor.